Skip to content

feat(runtime): host GuestExec layer + portable exit-signal error type (RIG-2493) - #702

Merged
mattwilkinsonn merged 2 commits into
mainfrom
compass-runner/rig-2493-u3-host-exec
Aug 30, 2026
Merged

feat(runtime): host GuestExec layer + portable exit-signal error type (RIG-2493)#702
mattwilkinsonn merged 2 commits into
mainfrom
compass-runner/rig-2493-u3-host-exec

Conversation

@rigel-mintaka

@rigel-mintaka rigel-mintaka commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

This PR is part of a stack containing 4 PRs:

  1. main
  2. feat(guestd): replace the Health-only stub with the V2b in-guest supervisor (RIG-2493) #701
  3. "feat(runtime): host GuestExec layer + portable exit-signal error type (RIG-2493)" (this PR)
  4. feat(runtime): fill MicroVMRuntime lifecycle methods (RIG-2493) #719
  5. test(runtime): shared ContainerRuntime contract suite across both backends (RIG-2493) #720

U3 + U3b of the frozen microVM Runner V2b plan (docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md, §Plan U3/U3b, §(c)/§(e)). The host-side client half of the exec control plane: a GuestExec layer over U1's generated GuestControl client, plus the backend-portable error type the runner's kill-classifier keys on.

U3b — portable exit-signal error (internal/runtime/exit_status_error.go, new)

ExitStatusError{Code int; Signal syscall.Signal} with Error(), in package runtime. A remote guest exec cannot forge an *exec.ExitError, so the microVM waitFunc constructs this instead for a signalled guest exit. internal/runner/agent_exec.go's isDeliberateKill is widened to errors.As on *runtime.ExitStatusError first (a non-zero signal ⇒ deliberate kill), then the existing *exec.ExitError SIGKILL branch unchanged — so the podman byte-path is byte-identical and only the microVM backend gets the new classification.

U3 — GuestExec layer (internal/runtime/microvm/exec.go, new)

Plain structs (ExecCall/ExecResult/StreamCall/ExitStatus) mirror the proto so runtime types don't leak into microvm (microvm must not import runtime; U4 makes runtime import microvm).

  • Exec (one-shot RPC): a non-zero exit is a successful ExecResult; a refusal/transport failure is an error; a host-side timeout → *microvm.TimeoutError.
  • ExecStream (bidi): opens the stream, sends StartExec, awaits ExecStarted before returning; per-exec goroutines pump the Stdin pipe → stdin frames (Closestdin_close + CloseRequest) and demux stdout/stderr response frames onto io.Pipe read ends, closing them on ExecExit.
  • GuestStream.Kill issues a Signal RPC bounded by killSignalTimeout (never blocks teardown past it); Wait blocks on the demux goroutine and returns ExitStatus{Code,Signal}. A ctx-cancel stream break reports SIGKILL — guestd reaps the child bound to the broken stream.

podman.go — funcs-backed ChildHandle

Adds unexported newChildHandleFuncs(kill, wait func() error) *ChildHandle plus killFunc/waitFunc fields. Kill/Wait/Terminate branch to the funcs path when killFunc != nil, else drive the original cmd/cancel path untouched (podman byte-unchanged). Terminate = kill then wait, returning the wait error (the exit status) when non-nil else the kill error — so a crash-vs-teardown consumer gets the exit signal.

Verification

go build ./internal/runtime/... ./internal/runner/... clean; go vet clean over runtime, runtime/microvm, runner. Tests (all hardware-independent, no microvm build tag, no KVM):

  • exec_test.go — fake GuestControl server on a unix listener over h2c Connect, dialed by a real client: one-shot non-zero exit is success + spec mapping; refusal is an error; one-shot timeout → *TimeoutError; stream demux ordering (interleaved frames land on the correct pipes, drained concurrently); stdin framing + Closestdin_close; Kill issues the Signal RPC and Wait unblocks on the signalled exit; ctx-cancel breaks the stream and Wait reports SIGKILL.
  • child_handle_test.gonewChildHandleFuncs: Kill invokes/propagates; Wait surfaces *ExitStatusError unchanged; Terminate return-value precedence.
  • deliberate_kill_test.goisDeliberateKill accepts a real *exec.ExitError from a SIGKILLed local child (podman-path regression guard) and *runtime.ExitStatusError{Signal: SIGKILL}, rejects a non-signal ExitStatusError, an unrelated error, and nil.

Ledger-impact: none

Spec-impact: none. Refs RIG-2493

Co-authored-by: Matt Wilkinson matt@rigel.build

@linear-code

linear-code Bot commented Aug 28, 2026

Copy link
Copy Markdown

RIG-2493

@github-actions

github-actions Bot commented Aug 28, 2026

Copy link
Copy Markdown

Compass engineering docs preview: https://compass-runner-rig-2493-u3-h.compass-eng-docs.pages.dev

Deployed from compass-runner/rig-2493-u3-host-exec at 3c87d57.

@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u2-guestd-supervisor branch from a66b253 to 23e0315 Compare August 28, 2026 04:12
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u3-host-exec branch from facc61c to 8a00c7e Compare August 28, 2026 04:15
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u2-guestd-supervisor branch from 23e0315 to 7e0a64e Compare August 28, 2026 04:35
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u3-host-exec branch from 8a00c7e to 869399a Compare August 28, 2026 04:37
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u2-guestd-supervisor branch from 7e0a64e to efbf696 Compare August 28, 2026 10:08
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u3-host-exec branch from 869399a to 81856f8 Compare August 28, 2026 10:09
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u2-guestd-supervisor branch from efbf696 to 8a86859 Compare August 28, 2026 11:08
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u3-host-exec branch from 81856f8 to 417292b Compare August 28, 2026 11:09
rigel-mintaka and others added 2 commits August 29, 2026 15:25
…rvisor (RIG-2493)

U2 of the frozen microVM Runner V2b plan (`docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md`, §Plan U2 / §(b)). Replaces the V2a `healthService` (which U1 left embedding `UnimplementedGuestControlHandler` to satisfy the widened interface) with the full `supervisor` implementing every `GuestControl` RPC.

### What

- **State gate** (`booting → ready → provisioned`, mutex-guarded): `Exec`/`ExecStream` refuse with `FailedPrecondition` until `Provision` opens the gate.
- **`Provision`** records `default_exec_uid` (validated non-zero) + `base_env`; a non-empty `nft_script` answers `Unimplemented` (V3's); a second call or a not-ready guest answers `FailedPrecondition`.
- **`Exec`** (one-shot): uid resolve (absent → session default, `0` → refused), env merge (exec keys win), stdin via `bytes.Reader` never argv, 8 MiB-capped stdout/stderr buffers (`ResourceExhausted` on overflow — the acknowledged divergence from the podman contract, OQ-E), guest-side timeout, non-zero exit is a **successful** `ExecResponse`, ctx-cancel → SIGKILL + reap.
- **`ExecStream`** (bidi): first frame must be `StartExec`; `ExecStarted` is emitted first; a shared send-mutex serializes the demuxed `stdout`/`stderr`/`ExecExit` down-frames; stdin frames + `StdinClose` half-close the child; a broken stream or ctx-cancel → SIGKILL + reap; the terminal `ExecExit` always comes from our own reap.
- **`Signal`**: `exec_id` → process-group signal; unknown/exited exec → no-op success; empty `exec_id` → `initiateStop` (the §(d) guest-stop path).
- **Stop → power-off**: `run()` derives a serving ctx wired to `stopServing`; after serve returns, an RPC-triggered stop with no serve error calls `powerOff()` (`syscall.Reboot(LINUX_REBOOT_CMD_POWER_OFF)`), the PID-1-legal shutdown. The Unix-signal path (`cmd/compass-guestd` `signal.NotifyContext`) is a **distinct** trigger and returns as before, per §(d).
- **Peer-CID guard**: `peerCIDListener` refuses any non-host CID before the first HTTP byte (hermetic non-vsock listeners are allowed); the handler carries `WithReadMaxBytes(16 MiB)` (OQ-E).
- **Boot nonce**: `cmdline.go` parses `compass.boot_nonce=<hex>` (absent → nil, empty/non-hex → error); the supervisor echoes it on `HealthResponse.boot_nonce` (U1's additive field) so Start binds the guest to the VM it launched (§(e)).

Boot steps 1–4 are byte-identical; only the serve step is retyped to `*supervisor` and gains the `powerOff` seam.

### Verification

`go build ./...` clean (whole module); `go test ./internal/guestd/...` ok; `go test -race ./internal/guestd/...` ok; `gofmt -l internal/guestd/` clean. The hermetic suite (`supervisor_test.go`) drives an in-memory h2c listener with real host child processes and covers every §(b) acceptance row (gate refusal, uid-0 refusal, default-uid resolution, stdin-not-argv, env merge, non-zero-exit success, stream demux ordering, signal-kills-live-child, signal-on-exited no-op, broken-stream reap, peer-CID pure function, RPC-stop → power-off).

### Guest PATH resolution (CI fix, folded)

`buildChild` spawned via `exec.Command(argv[0], …)`, whose bare-name resolution runs `LookPath` against guestd's OWN process environment — and guestd is PID 1 with no `PATH`, so a bare `argv[0]` (`echo`, `sh`, and in production `compass-agent`) never resolved: the first live KVM boot failed the exec rows with `executable file not found in $PATH`. The hermetic suite false-greened because it runs in-process with the test's ambient `PATH`. Fix (the container-baked-PATH analog, §(b)): `mergeEnv` floors a default `PATH=/bin:/usr/bin:/sbin:/usr/sbin` when neither the session base env nor the exec env supplies one, and `buildChild` resolves `argv[0]` against that merged `PATH` (via `resolveProgram`, honoring the session env, not the process env) — a name with a slash is used as-is, so absolute-path execs are unchanged. Regression: `TestExecResolvesBareCommandViaSessionPATH` (a base_env PATH pointing at a probe absent from the process PATH; fails before the fix) and `TestMergeEnvFloorsDefaultPATH`.

Ledger-impact: none

Spec-impact: none. Refs RIG-2493

Co-authored-by: Matt Wilkinson <matt@rigel.build>
… (RIG-2493)

U3 + U3b of the frozen microVM Runner V2b plan (`docs/designs/infra/runtime/compass-elastic-session-runtime/microvm-v2b-guest-supervisor-exec.md`, §Plan U3/U3b, §(c)/§(e)). The host-side client half of the exec control plane: a `GuestExec` layer over U1's generated `GuestControl` client, plus the backend-portable error type the runner's kill-classifier keys on.

### U3b — portable exit-signal error (`internal/runtime/exit_status_error.go`, new)

`ExitStatusError{Code int; Signal syscall.Signal}` with `Error()`, in package `runtime`. A remote guest exec cannot forge an `*exec.ExitError`, so the microVM `waitFunc` constructs this instead for a signalled guest exit. `internal/runner/agent_exec.go`'s `isDeliberateKill` is widened to `errors.As` on `*runtime.ExitStatusError` **first** (a non-zero signal ⇒ deliberate kill), then the existing `*exec.ExitError` SIGKILL branch **unchanged** — so the podman byte-path is byte-identical and only the microVM backend gets the new classification.

### U3 — GuestExec layer (`internal/runtime/microvm/exec.go`, new)

Plain structs (`ExecCall`/`ExecResult`/`StreamCall`/`ExitStatus`) mirror the proto so `runtime` types don't leak into `microvm` (`microvm` must not import `runtime`; U4 makes `runtime` import `microvm`).

- **`Exec`** (one-shot RPC): a non-zero exit is a successful `ExecResult`; a refusal/transport failure is an error; a host-side timeout → `*microvm.TimeoutError`.
- **`ExecStream`** (bidi): opens the stream, sends `StartExec`, **awaits `ExecStarted`** before returning; per-exec goroutines pump the `Stdin` pipe → stdin frames (`Close` → `stdin_close` + `CloseRequest`) and demux `stdout`/`stderr` response frames onto `io.Pipe` read ends, closing them on `ExecExit`.
- **`GuestStream.Kill`** issues a `Signal` RPC bounded by `killSignalTimeout` (never blocks teardown past it); **`Wait`** blocks on the demux goroutine and returns `ExitStatus{Code,Signal}`. A ctx-cancel stream break reports SIGKILL — guestd reaps the child bound to the broken stream.

### `podman.go` — funcs-backed ChildHandle

Adds unexported `newChildHandleFuncs(kill, wait func() error) *ChildHandle` plus `killFunc`/`waitFunc` fields. `Kill`/`Wait`/`Terminate` branch to the funcs path when `killFunc != nil`, else drive the original `cmd`/`cancel` path **untouched** (podman byte-unchanged). `Terminate` = kill then wait, returning the wait error (the exit status) when non-nil else the kill error — so a crash-vs-teardown consumer gets the exit signal.

### Verification

`go build ./internal/runtime/... ./internal/runner/...` clean; `go vet` clean over `runtime`, `runtime/microvm`, `runner`. Tests (all hardware-independent, no `microvm` build tag, no KVM):

- `exec_test.go` — fake `GuestControl` server on a unix listener over h2c Connect, dialed by a real client: one-shot non-zero exit is success + spec mapping; refusal is an error; one-shot timeout → `*TimeoutError`; stream demux ordering (interleaved frames land on the correct pipes, drained concurrently); stdin framing + `Close` → `stdin_close`; `Kill` issues the `Signal` RPC and `Wait` unblocks on the signalled exit; ctx-cancel breaks the stream and `Wait` reports SIGKILL.
- `child_handle_test.go` — `newChildHandleFuncs`: `Kill` invokes/propagates; `Wait` surfaces `*ExitStatusError` unchanged; `Terminate` return-value precedence.
- `deliberate_kill_test.go` — `isDeliberateKill` accepts a real `*exec.ExitError` from a SIGKILLed local child (podman-path regression guard) and `*runtime.ExitStatusError{Signal: SIGKILL}`, rejects a non-signal `ExitStatusError`, an unrelated error, and nil.

Ledger-impact: none

Spec-impact: none. Refs RIG-2493

Co-authored-by: Matt Wilkinson <matt@rigel.build>
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u2-guestd-supervisor branch from 8a86859 to e8df501 Compare August 29, 2026 19:29
@rigel-mintaka
rigel-mintaka force-pushed the compass-runner/rig-2493-u3-host-exec branch from 417292b to 3c87d57 Compare August 29, 2026 19:35
Base automatically changed from compass-runner/rig-2493-u2-guestd-supervisor to main August 30, 2026 04:15
@mattwilkinsonn
mattwilkinsonn merged commit 27c9411 into main Aug 30, 2026
19 of 20 checks passed
@mattwilkinsonn
mattwilkinsonn deleted the compass-runner/rig-2493-u3-host-exec branch August 30, 2026 04:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants